package com.jade.bss.admin.permission;

import java.util.List;

import com.jade.bss.admin.AdminException;

/**
 * The permission manager is a class that provides the function of permission entry
 * management.
 *
 * @author sky
 * @version 1.0 13-4-18 上午9:29
 */
public interface PermissionManager
{
    /**
     * Returns the permission entry with the specified ID.
     *
     * @param id permission id
     * @return the permission entry with the specified ID.
     */
    public PermissionEntry getPermission(int id);

    /**
     * Returns the permission entry with the specified name.
     *
     * @param name permission name
     * @return the permission entry with the specified name.
     */
    public PermissionEntry getPermission(String name);

    /**
     * Return the array of permission entries by the given the array of IDs.
     *
     * @param ids the array of IDs.
     * @return the array of permission entries.
     */
    public PermissionEntry[] getPermission(int[] ids);

    /**
     * Returns the list of all permission entries.
     *
     * @return the list of all permission entries.
     */
    public List<PermissionEntry> listPermission();

    /**
     * Add a new permission entry.
     *
     * @param permission the permission entry to be added.
     * @return the new permission entry's id
     * @throws AdminException if the operation can't be completed because some reasons, such as database error.
     */
    public int addPermission(PermissionEntry permission)
            throws AdminException;

    /**
     * Add a new permission with group
     *
     * @param permission the permission entry to be added.
     * @param groupId    group id
     * @return the new permission entry's id
     * @throws AdminException if the operation can't be completed because some reasons, such as database error.
     */
    public int addPermission(PermissionEntry permission, int groupId)
            throws AdminException;

    /**
     * Associate a permission to group
     *
     * @param permissionId permission id
     * @param groupId      group id
     * @throws AdminException f the operation can't be completed because some reasons, such as database error.
     */
    public void associate(int permissionId, int groupId)
            throws AdminException;

    /**
     * Associate an array of permissions to group
     *
     * @param permissionId the array of permission ids
     * @param groupId      group id
     * @throws AdminException f the operation can't be completed because some reasons, such as database error.
     */
    public void associate(int[] permissionId, int groupId)
            throws AdminException;

    /**
     * Dissociate a permission from group
     *
     * @param permissionId permission id
     * @throws AdminException f the operation can't be completed because some reasons, such as database error.
     */
    public void dissociate(int permissionId)
            throws AdminException;

    /**
     * Dissociate an array of permissions to group
     *
     * @param permissionId the array of permission ids
     * @throws AdminException f the operation can't be completed because some reasons, such as database error.
     */
    public void dissociate(int[] permissionId)
            throws AdminException;

    /**
     * Removes the permission entry with the specified ID.
     *
     * @param permissionId the ID of permission entry.
     * @throws AdminException if the operation can't be completed because some reasons, such as database error.
     */
    public void removePermission(int permissionId)
            throws AdminException;

    /**
     * Removes the permission entries by the given array of IDs.
     *
     * @param permissionIds the array of IDs.
     * @throws AdminException if the operation can't be completed because some reasons, such as database error.
     */
    public void removePermission(int[] permissionIds)
            throws AdminException;

    /**
     * Return the permission group with the specified ID.
     *
     * @param id permission group's ID
     * @return permission group
     */
    public PermissionGroup getGroup(int id);

    /**
     * Return the list of all permission groups.
     *
     * @return the list of all permission groups
     */
    public List<PermissionGroup> listGroup();

    /**
     * Adds a permission group.
     *
     * @param group permission group
     * @return group's ID
     * @throws AdminException name conflicted; unexpected error
     */
    public int addGroup(PermissionGroup group)
            throws AdminException;

    /**
     * Removes a permission group.
     *
     * @param id permission group's ID
     * @throws AdminException unexpected error
     */
    public void removeGroup(int id)
            throws AdminException;
}
